Generating Documentation with Sphinx

With Sphinx you can:

• Generate nicely formatted documentation in HTML and PDF
• Docstrings are usefull twice: when reading the code and when consulting the manual
• re-structured text (reST)
• Include LaTeX formula's
• Doc-string tests
• Used exstensively by other (scientific) Python modules

See Sphinx in action:

• http://sphinx-doc.org/examples.html

Examples:

• http://matplotlib.org/sampledoc/
• http://pythonhosted.org/an_example_pypi_project/index.html

Documentation:

• http://sphinx-doc.org/contents.html

First steps with Sphinx:

• http://sphinx-doc.org/tutorial.html

Python PEP-257: doc string conventions:

• http://legacy.python.org/dev/peps/pep-0257/

ReST

• http://docutils.sourceforge.net/docs/user/rst/quickref.html
• http://sphinx-doc.org/rest.html

Extensions for Sphinx

NumPy doc strings: numpydoc

• https://github.com/numpy/numpydoc
• https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

• While a rich set of markup is available, we limit ourselves to a very basic subset, in order to provide docstrings that are easy to read on text-only terminals
• The length of docstring lines should be kept to 75 characters to facilitate reading the docstrings in text terminals.

NumPy documentation conventions:

• Parameters (optional keyword arguments), Returns, Raises, Attributes (for classes), ...
• Including LaTeX formatted formula's
• Including examples
• example: https://github.com/numpy/numpy/blob/master/doc/example.py
• example: http://sphinx-doc.org/latest/ext/example_numpy.html

HTML slides with Hieroglyph

Hieroglyph is an extension for Sphinx which builds HTML slides from ReStructured Text documents.

• https://github.com/nyergler/hieroglyph
• http://docs.hieroglyph.io

Generate Sphinx documentation based on IPython notebooks

http://sphinx-ipynb.readthedocs.org/en/latest/index.html

Sphinx for Fortran

• https://github.com/TRACMASS/sphinx-fortran-extension
• http://www.ifremer.fr/vacumm/user.desc.fdoc.html

Publish documentation

You can use either Github's pages mechanism or Read the Docs.

• Read the Docs: http://dont-be-afraid-to-commit.readthedocs.org/en/latest/documentation.html
• Github gh-pages: http://raxcloud.blogspot.dk/2013/02/documenting-python-code-using-sphinx.html

Other documentation tools

Doxygen, supports more languages:

• http://www.stack.nl/~dimitri/doxygen/ https://github.com/doxygen/doxygen